Fix/issue 140 clarify commands location#2190
Fix/issue 140 clarify commands location#2190Tayyaba-Akbar956 wants to merge 10 commits intogithub:mainfrom
Conversation
* Add \docs/quickstart.md\: 4-step beginner flow with clear CLI vs AI command separation * Add \docs/vscode-usage.md\: step-by-step guide to install Copilot Chat, run \specify\ in terminal, and fix common errors * Update \README.md\ with links to both guides * Use newcomer-friendly tone with warnings, code blocks, and troubleshooting * Prevent users from typing \specify\ into Copilot Chat (common first-timer mistake) Closes github#140
There was a problem hiding this comment.
Pull request overview
Documentation update to address issue #140 by clarifying where Spec Kit CLI commands vs AI-assistant slash commands should be run (terminal vs chat), and by standardizing examples on the /speckit.* slash-command prefix.
Changes:
- Added a new VS Code usage guide explaining Copilot Chat setup and where to run CLI vs slash commands.
- Updated quickstart with a command-type reference table, troubleshooting, and revised examples using
/speckit.*. - Updated docs navigation to include the new VS Code guide.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/vscode-usage.md | New guide describing Copilot Chat setup and where to run CLI vs slash commands. |
| docs/toc.yml | Adds “VS Code Usage” to the Getting Started TOC. |
| docs/README.md | Updates docs index to include the new VS Code usage page. |
| docs/quickstart.md | Adds command-type clarification/table, troubleshooting, and updates examples to /speckit.*. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why
Agent-Logs-Url: https://github.com/Tayyaba-Akbar956/spec-kit/sessions/6753ecd1-6750-44a1-9e1b-3645b52f9bd0 Co-authored-by: Tayyaba-Akbar956 <193090017+Tayyaba-Akbar956@users.noreply.github.com>
…fy-command-instructions docs: fix Copilot review comments on quickstart and vscode-usage guides
|
Hi @mnriem! I've addressed all three Copilot review comments. The fixes have been merged into this branch and are reflected in the latest commits. Here's a quick summary of what was fixed:
Please let me know if anything else needs to be changed. Thanks! |
There was a problem hiding this comment.
Pull request overview
This PR updates the DocFX documentation to clarify where to run Spec Kit commands (terminal vs AI assistant slash commands), addressing confusion reported in issue #140 when users typed /specify in Copilot Chat and it was treated as plain text.
Changes:
- Add a new “VS Code Usage” doc page explaining command locations and Copilot Chat setup.
- Update
quickstart.mdwith a CLI vs slash-command reference table, updated examples using/speckit.*, and troubleshooting tips. - Update docs navigation/indexing to include the new VS Code page.
Show a summary per file
| File | Description |
|---|---|
| docs/vscode-usage.md | New guide explaining VS Code terminal vs Copilot Chat usage and setup. |
| docs/quickstart.md | Adds a command-type table, clarifies CLI vs slash commands, updates examples, and adds troubleshooting. |
| docs/toc.yml | Adds “VS Code Usage” to the Getting Started TOC. |
| docs/README.md | Lists the new vscode-usage.md file in the docs structure. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/4 changed files
- Comments generated: 5
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Use 'sh' code block instead of 'powershell' for cross-platform commands - Add OS-specific path examples for cd command - Wording fix: 'Open PowerShell' -> 'Open a terminal'
There was a problem hiding this comment.
Pull request overview
Updates Spec Kit documentation to clarify where users should run CLI commands vs AI assistant slash commands, addressing confusion reported in issue #140 (especially within VS Code / Copilot Chat).
Changes:
- Added a new VS Code usage guide explaining terminal vs Copilot Chat usage and how to enable Copilot Chat.
- Updated the quickstart to explicitly distinguish
specify(CLI) from/speckit.*(slash commands), including a quick reference table and troubleshooting notes. - Extended DocFX navigation to include the new VS Code usage guide.
Show a summary per file
| File | Description |
|---|---|
| docs/vscode-usage.md | New guide for VS Code users on installing/enabling Copilot Chat and where to run CLI vs slash commands. |
| docs/toc.yml | Adds “VS Code Usage” to the Getting Started section navigation. |
| docs/quickstart.md | Clarifies command locations (terminal vs AI assistant), updates examples to /speckit.*, and adds troubleshooting guidance. |
| docs/README.md | Documents the new VS Code usage page in the docs folder overview. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/4 changed files
- Comments generated: 2
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback
There was a problem hiding this comment.
Pull request overview
Updates the documentation to clarify where Spec Kit commands should be run (terminal CLI vs AI assistant slash commands) and resolves confusion around using /specify in GitHub Copilot Chat.
Changes:
- Added a dedicated VS Code usage guide explaining CLI vs slash commands and Copilot Chat setup.
- Updated Quick Start to consistently use
/speckit.*slash commands and added a quick reference table + troubleshooting notes. - Updated docs navigation to include the new VS Code guide.
Show a summary per file
| File | Description |
|---|---|
| docs/vscode-usage.md | New guide covering where to run commands in VS Code and how to enable Copilot Chat. |
| docs/quickstart.md | Clarifies CLI vs slash command usage, updates examples to /speckit.*, adds quick reference + troubleshooting. |
| docs/toc.yml | Adds the VS Code usage page to the “Getting Started” section. |
| docs/README.md | Updates docs index to include the new VS Code guide. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/4 changed files
- Comments generated: 2
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback
…ove broken python -m invocation
There was a problem hiding this comment.
Pull request overview
Documentation update to resolve issue #140 by clarifying where Spec Kit commands should be executed (terminal vs AI assistant chat), and by standardizing examples on the /speckit.* slash-command namespace for editor/assistant integrations.
Changes:
- Added a new VS Code–focused usage guide explaining command execution locations and Copilot Chat setup.
- Updated Quick Start to distinguish CLI
specifyusage from/speckit.*slash commands, plus added a quick reference table and troubleshooting notes. - Updated docs navigation to include the new VS Code guide.
Show a summary per file
| File | Description |
|---|---|
| docs/vscode-usage.md | New guide for VS Code + Copilot Chat setup and where to run CLI vs slash commands. |
| docs/quickstart.md | Adds clearer CLI vs slash-command guidance, updated examples, and troubleshooting section. |
| docs/toc.yml | Adds “VS Code Usage” to the Getting Started navigation. |
| docs/README.md | Lists the new vscode-usage.md in the docs structure section. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/4 changed files
- Comments generated: 2
| ### Where to run commands: Terminal vs AI Assistant | ||
|
|
||
| - **CLI commands** (e.g., `specify init`, `specify check`): Run in the VS Code integrated terminal. These are shell commands that execute on your machine. | ||
| - **Slash commands** (e.g., `/speckit.specify`, `/speckit.plan`): Run inside an AI assistant chat window (like GitHub Copilot Chat). These are consumed by the AI assistant, not executed as shell commands. | ||
|
|
There was a problem hiding this comment.
The VS Code guide explains where to run slash commands, but it doesn’t explain what makes /speckit.* commands show up in Copilot Chat. For Copilot, these commands come from the prompt files generated into .github/prompts/ during specify init (choose --ai copilot / select Copilot in the init prompt) and they’re only available when VS Code is opened on that project folder. Adding a short note (and a troubleshooting item for “/speckit.* is treated as plain text”) would directly address the issue reporter’s failure mode.
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why
…ubleshooting, and fix minor formatting issues
There was a problem hiding this comment.
Pull request overview
Clarifies where to run Spec Kit commands (terminal vs AI assistant chat) to address confusion from issue #140, and standardizes examples around the /speckit.* slash-command prefix.
Changes:
- Added a new VS Code usage guide explaining CLI vs slash commands and Copilot Chat setup/troubleshooting.
- Updated Quick Start to clearly distinguish command types, add a quick reference table, and update examples to
/speckit.*. - Updated DocFX navigation to include the new VS Code guide.
Show a summary per file
| File | Description |
|---|---|
| docs/vscode-usage.md | New guide detailing where to run CLI vs slash commands, Copilot Chat setup, and troubleshooting. |
| docs/quickstart.md | Adds command-type clarification + table and updates examples to /speckit.* with troubleshooting notes. |
| docs/toc.yml | Adds VS Code Usage entry under Getting Started. |
| docs/README.md | Documents the new vscode-usage.md file in the docs structure list. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/4 changed files
- Comments generated: 0 new
Summary
Fixes issue #140 - Unclear instructions on where to run
/specifycommand.Problem
New users were confused about where to run spec-kit commands:
/specifyin Copilot Chat treated it as plain text, not a commandSolution
specify) vs slash commands (/speckit.specify)/speckit.prefixFiles Changed